;================================================================;
;=                                         __  _________        =;
;=     _                                  /. \/         \       =;
;=    / \ |                  |       o---->    | |    \  \      =;
;=    |   | _             _  |  _         \__/\||__ | |_  \     =;
;=    |   |/ \ /\  |^v^| /_\ | /_\ /\ |^\      ||  / /  \ |     =;
;=    \_/ |  | \/| |   | \_  | \_  \/ | |   -=(_)\_||  /| |     =;
;=                                               \(_)\ \_/      =;
;=                                                  \ \____     =;
;=                                                   \          =;
;=                                                    \____     =;
;=    Shawn Lindberg 1998                                       =;
;=                                                              =;
;================================================================;



Tutorial for Chameleon v 1.0
by Shawn Lindberg

Table of Contents

1.	A Note on Chameleon
2.	How to Use Chameleon
	(a) Requirements
	(b) Turning Chameleon On
	(c) Clearing Buffers
	(d) Sprite Format
	(e) Drawing Sprites
	(f) Erasing Sprites
	(g) Turning Chameleon Off
3.	Endnote

1. A Note on Chameleon
----------------------
Chameleon is the first 4 color greyscale sprite system for the TI-83.  This file will help you use it to make you own greyscale games, or other applications.  Please give me credit, this is a great service I am doing for the TI community.  Even though this system uses interrupts, it will slow down your programs, which will just mean that you'll have to change the speeds of your pauses, but that is something you must play with. =)  It is also important to know that this is not perfect, but it can't be, because of the hardware on the TI-83.  Needless to say, this is a remarkable achievement!  Enjoy!

2. How to Use Chameleon
-----------------------
Chameleon is not really harder to use than your average sprite routine, in fact, many of the tasks are done for you.  This sections will hopefully allow you to use Chameleon to its optimum.

2. (a)  Requirements
--------------------
There are some requirements for Chameleon to perform properly.  They are as follows:

1.	Ram Areas 8600h through 8700h, and 877ah through 87E0h should not be written to.  This is the closest estimate I can get of the ending of the routine.  To be safe, I would keep some space in between that and my data if I were you.  If anyone finds out the exact location, I would appreciate knowing!!!
2.	All of area Safe Ram Area 1 (otherwise known as savesscreen) or, the area from 8265h to 8565h (768 bytes starting at 8265h) must NOT be used for anything.  It is one of the 2 buffers required by Chameleon.

2. (b)  Turning Chameleon On
----------------------------
To turn Chameleon on, you must call ChameleonOn, and the calc will automatically start flashing the layers on the screen.  Its that simple!

2. (c)  Clearing Buffers
------------------------
Since there is an extra buffer in the Chameleon system, it is rather logical you might need to clear it.  For that reason, I have created a very small routine for exactly that purpose.  To clear the first layer (the graph buffer), just do this:
call _grbufclr
To clear the second buffer, just do this:
call BuffClr
Now, the buffer will be set with 0.

2. (d)  Sprite Format
---------------------
In order for the sprite routine of Chameleon to put your sprites correctly (and to keep it from freezing) there is a format that is recommended for your asm data.  Some of it is suggested format, and other parts are required.  I will tell you which it is. =)

The first part of a sprite is its "header".  It is simply 2 bytes of information that the sprite routine will use to read the size of the sprite.  The first byte is the number bytes wide a sprite is.  The second number is the number of rows the sprite is tall.
Ex.
	.db	1,8     ;8x8 sprite
Ex.	.db	2,15	;16x15 sprite
Keep in mind that the specifics are not important.  You can not use the comma, and add another .db, or you can change the format of the numbers, such as making them hex or binary, just as long as they are the right values.  Note:  The first number cannot be bigger than 12, and the second number cannot be bigger than 64.  These two bytes of data must come right after the label for your sprite.  In other words, you will put into ix the location of the first byte.

Now, for the actual image.  It consists of 2 parts, layer 1, and layer 2.
Ex.	.db	1,8	;8x8 sprite
	.db	00000000b	;layer 1
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b

	.db	00000000b	;layer 2
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
	.db	00000000b
It is important to remember, that again, the exact format of the numbers and the bytes is not important, what is important is that there are the correct number of bytes, and that you have both layers.  Now, you need to know how to place colors.

			Color	 
	| White | Light Grey | Dark Grey | Black |
      |-------------------------------------------
      |1|  Off  |    On      |    Off    |  On   |
Layer |-|-----------------------------------------
      |2|  Off  |    Off     |    On     |  On   |
      |-------------------------------------------

This table shows how to turn pixels to different colors.  To make a pixel white, it must be off in both layers, to make it black, it must be on in both layers, to make a pixel light grey, it must be on in the first and off in the second, and to make it dark grey, it must be off in the first layer and on in the second.

How much memory does each sprite take up.  Well, it's rather simple.  Just multiply the first two bytes (the size) and add 2.  That is how many bytes the sprite will take up when compressed using Squish, or Devpac83, or something similar.  That is the image format!

2. (e)  Drawing Sprites
-----------------------
Once you have your sprite data somewhere in your program, you are ready to draw your greyscale sprite.  It is not very hard, it just involves setting some "parameters".  In the a register, you must have your x coordinate for your sprite.  You must ld to e your y coordinate, and in d, you must put 1, since you are drawing.  Lastly you must put the pointer to the sprite in ix.  Then you call Chameleon.
Ex.	ld a,5		;x=5
	ld e,7		;y=7 (6 rows from the top)
	ld d,1		;this tells Chameleon to draw the sprite
	ld ix,Sprite	;this is the label of your sprite
	call Chameleon	;this will put the sprite in the buffers
This, in case you couldn't tell, will draw Sprite at 5,7 on the screen (in the buffers).  None of these may be missing, or it won't work.
Note:  This routine will not replace any pixels already turned on in the field of your sprite.  All pixels that were on before the draw will be on after the draw.

2. (f)  Erasing Sprites
-----------------------
Erasing sprites is the same as drawing them, except that you must ld to d 2.  It will erase the pixels that are on in your sprite.
Ex.	ld a,5		;x=5
	ld e,7		;y=7 (6 rows from the top)
	ld d,2		;this tells Chameleon to erase the sprite
	ld ix,Sprite	;this is the label of your sprite
	call Chameleon	;this will put the sprite in the buffers
This will remove the from the buffers all pixels that are on in your sprite.  If you change the x and y, it may erase something other than you intended.  If you have a 8x8 block of pixels, and in the same location remove a block of 8x8 pixels, all of which are turned on, the end result will be that the 8x8 block of pixels in the buffer will now be off.

2. (g)  Turning Chameleon Off
-----------------------------
You don't need to call anything to turn off Chameleon.  However, you mush include a set statsvalid,(iy+statflags) and an im 1, like this:
	set statsvalid,(iy+statflags)
	im 1
That will turn Chameleon off.

3.  Endnote
-----------
This is the best way to make greyscale graphics yet.  There is very little room for improvement, since the hardware requires certain parts to be exact.  I will update this source if bugs are found, but I am not responsible for any side effects of my code being changed.  Also, it will not be very hard for me to tell if my code is being stolen, so I advise not doing it.  I hope this system stimulates greyscale games, and that I nobody finds any bugs.

--Shawn Lindberg